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ABOUT THIS CHAPTER 


The Color Manager supplies color-selection support for Color QuickDraw on the 
Macintosh II. The software described in this chapter allows specialized 
applications to fine-tune the color-matching algorithms, and also provides 
utility functions that are rarely used by applications. 


An understanding of Color QuickDraw concepts, terminology, and data structures 
is essential when using the material in this chapter. You should be familiar 
with RGB color, pixel maps, pixel patterns, and other material introduced in the 
Color QuickDraw chapter. You should also be familiar with the material in the 
Graphics Devices chapter, since the Color Manager routines work on the device 
level. 


Keep in mind that Color Manager routines are the intermediary between high-level 
software such as Color QuickDraw, the Palette Manager, and the Color Picker, and 
the lower-level video devices. The majority of applications will never need to 
use the Color Manager routines directly. 


Reader's guide: The material in this chapter is largely for informational 
purposes only, since Color QuickDraw, the Palette Manager, 
and the other color Toolbox routines provide a detailed and 
consistent way to add color to Macintosh programs. 
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ABOUT THE COLOR MANAGER 


The Color Manager is optimized to work with graphics hardware that utilizes a 
Color Look-up Table (CLUT), a data structure that maps color indices, specified 
using QuickDraw, into actual color values. The exact color capabilities of the 
Macintosh II depend on the particular video card used. There are three kinds of 
devices: 


e CLUT devices contain hardware that converts an arbitrary pixel value 
stored in the frame buffer to some actual RGB video value, which is 
changeable. The pixel value could be the index to any of the colors 
in the current color set for the device, and the color set itself 
can be changed. 

¢ Fixed devices also convert a pixel value to some actual RGB video 
value, but the hardware colors can't be changed. The pixel value 
could be the index to any of the colors in the color set, but the 
color set itself always remains the same. 

¢ Direct devices have a direct correlation between the value placed in 
the frame buffer and the color you see on the screen. The value placed 
in the frame buffer would produce the same color every time. Direct 
devices aren't supported in the initial release of Color QuickDraw. 


Applications that limit themselves to a small set of colors can use them simply 
and easily from QuickDraw, with a minimum of overhead. Color QuickDraw accesses 
the Color Manager to obtain the best available color matches in the lookup 
table. Applications such as color painting and animation programs, which need 
greater control over the precise colors they use, can use the Palette Manager to 
allocate part of the color table for their own exclusive use. The Palette 
Manager, described in a later chapter, is useful for most applications that use 
shared color resources, imaging, or color table animation. The Palette Manager 
is used whenever color is used for objects within windows, while the Color 
Manager operates on the device level. 


Note: Palette Manager routines operate transparently across multiple 
screens, while Color Manager routines do not. Therefore, always 
use Palette Manager routines for applications that will run on 
multiple screens or in a multitasking environment. 


The sections that follow describe how the Color Manager converts the RGB values 
specified using Color QuickDraw into the actual colors available on a device. 
The pixel value, specifying the number of bits per pixel, is set using the 
Control Panel. 


Graphics Devices 


As with Color QuickDraw, the Color Manager accesses a particular graphics device 
through a data structure known as a gDevice record. Each gDevice record stores 
information about a particular graphics device; after this record is 
initialized, the device itself is known to the Color Manager and QuickDraw as a 
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gDevice. See the Graphics Devices chapter for more details on gDevice format and 
on the routines that allow an application to access a given device. Remember 
that a gDevice is a logical device, which the software treats the same whether 
it is a video card, a display device, or an offscreen pixel map. 


Color Table Format 


The complete set of colors in use at a given time for a particular gDevice is 
Summarized in a color table record. Its format is as follows: 


TYPE 
CTabHandle = “CTabPtr; 
CTabPtr = “ColortTable; 
ColorTable = RECORD 


ctSeed: LONGINT; {unique identifier from table} 
ctFlags: INTEGER; {high bit is set for a gDevice, } 
{ clear for a pixMap} 
ctSize: INTEGER; {Number of entries in table-1} 
ctTable: cSpecArray 
END; 


Field descriptions 


ctSeed The ctSeed field is similar to a version identifier number for 
a color table. If a color table is created by an application, it 
should call GetCTSeed to obtain this identifier. The ctSeed should 
be some unique number higher than minSeed, a predefined constant 
with a value of 1023. If a color table is created from a resource, 
its resource number will be used as the initial ctSeed. For 'CLUT' 
resource, the range of resource numbers should be 09-1023. 


ctFlags The ctFlags field is significant for gDevices only. It contains 
flags that describe the format of the ctTable. Currently, only 
the high bit is defined; all others are reserved. Color tables 
that are part of the gDevice structure always have this bit set. 
Color tables that are part of pixMaps have this bit clear. Each 
gDevice has its own pixMap, which has a color table. 


ctSize The ctSize field contains the number of entries in the color 
table minus one. All counts on color table entries are zero based. 


ctTable The ctTable field contains a cSpecArray, which is an array of 
ColorSpec entries. Notice that each entry in the color table is 
a ColorSpec, not simply an RGBColor. The type ColorSpec is 
composed of an integer value and an RGB color, as shown in the 
following specification. A color table may include a number of 
ColorSpec records. 


TYPE 
cSpecArray = ARRAY [0..0] OF ColorSpec; 
ColorSpec = RECORD 
value : INTEGER; {Color representation} 
rgb : RGBColor {Color value} 
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END; 


RGBColor = RECORD 
red : INTEGER; {Red component} 
green : INTEGER; {Green component} 
blue : INTEGER {Blue component} 
END; 


In gDevice color tables, the colorSpec.value field is reserved for use by the 
Color Manager and Palette Manager. Their interpretation and values are different 
than the color tables contained in pixMaps. 


Thinimwm seed value + 1024 
significant Cor gDeviees only; otherwise 0 
number of color table elements -1 


ctTable 
[cB per Array] 


EGEColor 


Figure 1-Color Table Format 
Figure 1—Color Table Format 


Note that the colorSpec.value field of the record is only word size (16 bits), 
even though color index values (as returned by Color2Index) may be long words. 
The current implementation of Color QuickDraw only supports 16 bits. The 
components in an RGBColor are left-justified rather than right-justified in a 
word. Video drivers should respect this convention and extract the appropriate 
number of bits from the high order side of the component. For example, the Apple 
Graphics Card uses only the most significant eight bits of each component of the 
RGBColor record. 


Inverse Tables 


Reader's guide: The material in this section is provided for informational 
and debugging purposes, since most programs won't need to 
use inverse tables. 
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For normal drawing, Color QuickDraw takes all specifications as absolute RGB 
triples, by means of the RGBColor record. Internally, these absolute 
specifications are converted to the appropriate values to be written into the 
video card. For direct devices, the RGB is separated into its red, green, and 
blue components, and each of these is written to the video card. On CLUT and 
fixed devices, however, there isn't always a direct relationship between the 
specified RGB and the index value written into the frame buffer; in fact, on 
CLUT devices, the best-match index value may change dynamically as the colors 
available in the hardware are changed. On these types of devices, Color 
QuickDraw uses the Color Manager to find the best matches among the colors 
currently available. 


The method used to determine the best available match can be specified by the 
application or the system on a gDevice by gDevice basis. By default, on CLUT and 
fixed devices, a special data structure called an inverse table is created. An 
inverse table is a table arranged in such a manner that, given an arbitrary RGB 
color, the pixel value can be very rapidly looked up. 


In the default case, a certain number of the most significant bits of red, 
green, and blue are extracted, then concatenated together to form an index into 
the inverse table. At this location is the "best" match to the specified color. 
The number of bits per color channel that are used to construct this index is 
known as the resolution of the inverse table, and can be 3, 4, or 5 bits per 
channel. As the resolution of the inverse table increases, the number of 
permutations of possible colors increases, as does the size of the inverse 
table. Three-bit tables occupy 512 bytes, 4-bit tables (the default) occupy 4K 
bytes, and 5-bit tables occupy 32K bytes. 


A disadvantage of this method is that certain colors that are "close" together 
can become hidden when they differ only in bits that weren't used to construct 
the inverse table index. For example, even if the color table were loaded with 
256 levels of gray, a 4-bit inverse table can only discriminate among 16 of the 
levels. To solve this problem without having to use special-case sets of colors 
with hidden colors, inverse tables carry additional information about how to 
find colors that differ only in the less significant bits. As a result, when the 
Color2Index routine is called, it can find the best match to the full 48-bit 
resolution available in a colorSpec. Since examining the extra information takes 
time, certain parts of Color QuickDraw, notably drawing in the arithmetic 
transfer modes, don't use this information, and hence won't find the hidden 
colors. 


In most cases, when setting colors using RGBForeColor and RGBBackColor, and when 
using CopyBits to transfer pixMaps, inverse tables of four bits are sufficient. 
When using arithmetic transfer modes with certain color tables that have 
closely-spaced colors, the screen appearance may be improved by specifying 
inverse tables at 5-bit resolution. Because the format of inverse tables is 
subject to change in the future, or may not be present on certain devices, 
applications should not assume the structure of the data. 


The data in inverse tables remains valid as long as the color table from which 
it was built remains unchanged. When a color table is modified, the inverse 
table must be rebuilt, and the screen should be redrawn to take advantage of 
this new information. Rather than being reconstructed when the color table is 
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changed, the inverse table is marked invalid, and is automatically rebuilt when 
next accessed. 


Rather than testing each entry of the color table to see if it has changed, the 
color-matching code compares the ctSeed of the current gDevice's colorTable 
against the iTabSeed of that gDevice's inverse table. Each routine that modifies 
the colorTable (with the exception of RestoreEntries) increments the ctSeed 
field of that colorTable. If the ctSeed and the iTabSeed don't match, the 
inverse table is reconstructed for that gDevice. 


Note: Under normal circumstances, all invalidations are posted and serviced 
transparently to the application. This method of invalidation is the 
same as that used to invalidate expanded patterns and cursors elsewhere 
in Color QuickDraw. 


In certain cases, it may be useful to override the inverse table matching code 
with custom routines that have special matching rules. See the section titled 
"Custom Search and Complement Procedures" for more details. 


The Color Manager performs a color table look-up in the following manner: 


1. Builds a table of all possible RGB values; 

2. For each position in the table, attempts to get the closest match; 

3. Reduces the resolution of the lookup to four bits when constructing 
the table, but later adds information to get a better resolution. 


The Color Manager performs this table-building sequence whenever colors are 
requested by Color QuickDraw, the Color Picker, or the Palette Manager. This 
isn't the only color matching method available; a custom search procedure, for 
example, may not have an inverse table. (See the section titled "Custom Search 
and Complement Procedures" for more information.) However, inverse tables are 
the default method for color matching. 


When using an inverse table, the table is indexed by concatenating together the 
high-order bits of the three desired color components; iTabRes tells how many 
bits of each component are significant. The format of an inverse table is shown 
below: 


TYPE 
ITabHandle = “ITabPtr; 
ITabPtr = “ITab; 
ITab = RECORD 
iTabSeed: LONGINT; {copy of color table seed} 
iTabRes: INTEGER; {resolution of table} 


iTTable: ARRAY[@..0] OF SignedByte {byte color } 
{ table index values} 
END; 


The size of an index table in bytes is 2*3*iTabRes. The table below shows a 
sample index table: 


resolution RGB color inverse-table size 
index 
4-bit red=$1234, 
green=$5678, 
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blue=$9ABC $0159 2°12 = 4K bytes 
5-bit red=$1234, 

green=$5678, 

blue=$9ABC $0953 2°15 = 32K bytes 


MakeITable only supports 3-bit, 4-bit, and 5-bit resolution. Five bits is the 
maximum possible resolution, since the indices into a 6-bit table would have to 
be 18 bits long, more than a full word. 
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USING THE COLOR MANAGER 


In the simplest cases, use of the Color Manager is transparent when invoking the 
new Color QuickDraw routines. Using RGBForeColor and RGBBackColor, the program 
requests an RGB color for either the foreground or background. For instance, the 
following code requests an RGB color of red and sets it in the cGrafPort: 


myColor.red:=$FFFF; 
myColor.green:=0; 

myColor.blue:=0; 
RGBForeColor(myColor); {set pen red} 
FrameRect(myRect); {draw in red} 


Internally the Color Manager finds the best match to a color in TheGdevice's 
current color table, and sets up the current cGrafPort to draw in this color. At 
this point, drawing operations can proceed using the selected colors. 


The Color Manager routines described in this chapter are designed to operate on 
a single gDevice. The Palette Manager can perform most of these operations 
across multiple gDevices. Since the Palette Manager provides more general and 
portable functionality, applications should use Palette Manager routines 
whenever possible. 


The SetEntries routine is used to change any part of or all of the entries ina 
device's hardware Color Look-Up Table. The SaveEntries and RestoreEntries 
routines can make temporary changes to the color table under very specialized 
circumstances (such as a color selection dialog within an application). These 
routines aren't needed under normal application circumstances. 


SaveEntries allows any combination of colorSpecs to be copied into a special 
colorTable. RestoreEntries replaces the table created by SaveEntries into the 
graphics device. Unlike SetEntries, these routines don't perform invalidations 
of the device's colorTable, so they avoid causing invalidations of cached data 
structures. When these routines are used, the application must take 
responsibility for rebuilding and restoring auxiliary structures as necessary. 


By convention, when using SetEntries or RestoreEntries, white should be located 
at color table position 0, and black should be stored in the last color table 
position available, whether it is 1, 3, 15, or 255. The Palette Manager also 
enforces this convention. 


For precise control over color, or for dedicated color table entries, the Color 
Manager routines maintain special information in device color tables. Using 
ProtectEntry and ReserveEntry, an entry may be protected, which prevents 
SetEntries from further changing the entry, or reserved, which makes the entry 
unavailable to be matched by RGBForeColor and RGBBackColor. Routines that change 
the device table (SetEntries, ProtectEntry, and ReserveEntry, but not 
RestoreEntries) will perform the appropriate invalidations of QuickDraw data 
structures. The application must then redraw where necessary. 
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To inquire if a color exists in a color table, use RealColor. This tells whether 
an arbitrary color actually exists in the table for that gDevice. 


Color2Index returns the index in the current device's colorTable that is the 
best match to the requested color. Index2Color performs the opposite function—it 
returns the RGB of a particular index value. These routines can be useful when 
making copies of the screen frame buffer. InvertColor finds the complement of 
the provided color. GetSubTable performs a group Color2Index on a colorTable. 
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COLOR MANAGER ROUTINES 


The routines used for color drawing are covered in the chapter "Color 
QuickDraw". The Color Manager includes routines for color conversion, color 
table management, and error handling. 


Color Conversion 
FUNCTION Color2Index (rgb: RGBColor): LONGINT; 


The Color2Index routine finds the best available approximation to a given 
absolute color, using the list of search procedures in the current device 
record. It returns a longint, which is a pixel value padded with zeros in the 
high word. Since the colorSpec.value field is only a word, the result returned 
from Color2Index must be truncated to fit into a colorSpec. In pixMaps the 
.value is the low-order word of this index. 


Color2Index shouldn't be called from a custom search procedure. 
PROCEDURE Index2Color (index: LONGINT; VAR rgb: RGBColor); 


The Index2Color routine finds the RGB color corresponding to a given color table 
index. The desired pixel value is passed and the corresponding RGB value is 
returned in RGB. The routine takes a longint, which should be a pixel value 
padded with zeros in the high word (normally the compiler does this 
automatically). Normally, the RGB from the current device color table 
corresponding to the index is returned as the RGBColor. Notice that this is not 
necessarily the same color that was originally requested via RGBForeColor, 
RGBBackColor, SetCPixel, or Color2Index. This RGB is read from the current 
gDevice color table. 


PROCEDURE InvertColor (VAR theColor: RGBColor); 


The InvertColor routine finds the complement of an absolute color, using the 
list of complement procedures in the current device record. The default 
complement procedure uses the 1's complement of each component of the requested 
color. 


FUNCTION RealColor (color: RGBColor) : BOOLEAN; 


The RealColor routine tells whether a given absolute color actually exists in 
the current device's color table. This decision is based on the current 
resolution of the inverse table. For example, if the current iTabRes is four, 
RealColor returns TRUE if there exists a color that exactly matches the top four 
bits of red, green, and blue. 


PROCEDURE GetSubTable (myColors: CTabHandle; iTabRes: INTEGER; 
targetTbl: CTabHandle) ; 
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The GetSubTable routine takes a ColorTable pointed at by myColors, and maps each 
RGB value into its nearest available match for each target table. These best 
matches are returned in the colorSpec.value fields of myColors. The values 
returned are best matches to the RGBColor in targetTbl and the returned indices 
are indices into targetTbl. Best matches are calculated using Color2Index and 
all applicable rules apply. A temporary inverse table is built, and then 
discarded. ITabRes controls the resolution of the iTable that is built. If 
targetTbl is NIL, then the current device's color table is used, and the 
device's inverse table is used rather than building a new one. To provide a 
different resolution than the current inverse table, provide an explicit 
targetTbl parameter; don't pass a NIL parameter. 


Warning: Depending on the requested resolution, building the inverse table 
can require large amounts of temporary space in the application 
heap: twice the size of the table itself, plus a fixed overhead 
for each inverse table resolution of 3—15K bytes. 


PROCEDURE MakeITable (colorTab: CTabHandle; inverseTab: ITabHandle; 
res: INTEGER); 


The MakeITable routine generates an inverse table based on the current contents 
of the color table pointed to by CTabHandle, with a resolution of res bits per 
channel. Reserved color table pixel values are not included in the resultant 
color table. MakeITable tests its input parameters and will return an error in 
QDError if the resolution is less than three or greater than five. Passing a NIL 
parameter to CTabHandle or ITabHandle substitutes an appropriate handle from the 
current gDevice, while passing 0 for res substitutes the current gDevice's 
preferred table resolution. These defaults can be used in any combination with 
explicit values, or with NIL parameters. 


This routine allows maximum precision in matching colors, even if colors in the 
color table differ by less than the resolution of the inverse table. Five-bit 
inverse tables are not needed when drawing in normal QuickDraw modes. However, 
the new QuickDraw transfer modes (add, subtract, blend, etc.) may require a 
5-bit inverse table for best results with certain color tables. MakeITable 
returns a QDError if the destination inverse table memory cannot be allocated. 
The 'mitq' resource governs how much memory is allocated for temporary internal 
structures; this resource type is for internal use only. 


Warning: Depending on the requested resolution, building the inverse table 
can require large amounts of temporary space in the application 
heap: twice the size of the table itself, plus a fixed overhead 
for each inverse table resolution of 3—15K 

bytes. 


Color Table Management 
FUNCTION GetCTSeed : LONGINT; 


The GetCTSeed function returns a unique seed value that can be used in the 
ctSeed field of a color table created by an application. This seed value 
guarantees that the color table will be recognized as distinct from the 
destination, and that color table translation will be performed properly. The 
return value will be greater than the value stored in minSeed. 
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PROCEDURE ProtectEntry (index: INTEGER; protect: BOOLEAN) ; 


The ProtectEntry procedure protects or removes protection from an entry in the 
current device's color table, depending on the value of the protect parameter. 
A protected entry can't be changed by other clients. It returns a protection 
error if it attempts to protect an already protected entry. However, it can 
remove protection from any entry. 


PROCEDURE ReserveEntry (index: INTEGER; reserve: BOOLEAN) ; 


The ReserveEntry procedure reserves or dereserves an entry in the current color 
table, depending on the value of the reserve parameter. A reserved entry cannot 
be matched by another client's search procedure, and will never be returned to 
another client by Color2Index or other routines that depend on it 

(such as RGBForeColor, RGBBackColor, SetCPixel, and so forth). You could use 
this routine to selectively protect a color for color table animation. 


ReserveEntry copies the low byte of gdID into the low byte of ColorSpec.value 
when reserving an entry, and leaves the high byte alone. It acts like a 
selective protection, and does not allow any changes if the current gdID is 
different than the one in the colorSpec.value field of the reserved entry. If a 
requested match is already reserved, ReserveEntry returns a protection error. 
Any entry can be dereserved. 


PROCEDURE SetEntries(start, count: INTEGER; aTable: CSpecArray) ; 


The SetEntries procedure sets a group of color table entries for the current 
gDevice, starting at a given position for the specified number of entries. The 
pointer aTable points into a cSpecArray, not into a color table. The 
colorSpec.value field of the entries must be in the logical range for the target 
card's assigned pixel depth. Thus, with a 4-bit pixel size, the colorSpec.value 
fields should be in the range 1 to 15. With an 8-bit pixel size the range is 0 
to 255. Note that all values are zero-based; for example, to set three entries, 
pass two in the count parameter. 


Note: Palette Manager routines should be used instead of the SetEntries 
routine for applications that will run in a multiscreen or 
multitasking environment. 


The SetEntries positional information works in logical space, rather than in the 
actual memory space used by the hardware. Requesting a change at position four 
in the color table may not modify color table entry four in the hardware, but it 
does correctly change the color on the screen for any pixels with a value of 
four in the video card. The SetEntries mode characterized by a start position 
and a length is called sequence mode. In this case, new colors are sequentially 
loaded into the hardware in the same order as the aTable, the clientID fields 
for changed entries are copied from the current device's gdID field, and the 
colorSpec.value fields are ignored. 


The other SetEntries mode is called index mode. It allows the cSpecArray to 
specify where the data will be installed on an entry-by-entry basis. To use this 
mode, pass —1 for the start position, with a valid count and a pointer to the 
cSpecArray. Each entry is installed into the color table at the position 
specified by the colorSpec.value field of each entry in the cSpecArray. In the 
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current device's color table, all changed entries' colorSpec.value fields are 
assigned the gdID value. 


When color table entries are changed, all cached fonts are invalidated, and the 
seed number is changed so that the next drawing operation will rebuild the 
inverse table. If any of the requested entries are protected or out of range, a 
protection error is returned, and nothing happens. If a requested entry is 
reserved, it can only be changed if the current gdID matches the low byte of the 
intended ColorSpec.value field. 


PROCEDURE SaveEntries (srcTable: CTabHandle; ResultTable: CTabHandle; 
VAR selection: ReqListRec) ; 


SaveEntries saves a selection of entries from srcTable into resultTable. The 
entries to be set are enumerated in the selection parameter, which uses the 
ReqListRec data structure shown below. (These values are offsets into 
colorTable, not the contents of the colorSpec.value field. ) 


TYPE 
ReqListRec = RECORD 
reqLSize: INTEGER; {request list size —1} 
reqLData: ARRAY [0..0] of INTEGER {request list data} 
END; 


If an entry is not present in srcTable, then that position of the requestList is 
set to colRegErr, and that position of resultTable has random values returned. 
If one or more entries are not found, then an error code is posted to QDError; 
however, for every entry in selection which is not colRegErr, the values in 
resultTable are valid. Note that srcTable and selection are assumed to have the 
same number of entries. 


SaveEntries optionally allows NIL as its source color table parameter. If NIL is 
used, the current device's color table is used as the source. The output of 
SaveEntries is the same as the input for RestoreEntries, except for the order. 


PROCEDURE RestoreEntries (srcTable:CTabHandle;DstTable:CTabHandle; 
VAR selection:ReqListRec) ; 


RestoreEntries sets a selection of entries from srcTable into dstTable, but 
doesn't rebuild the inverse table. The dstTable entries to be set are enumerated 
in the selection parameter, which uses the ReqListRec data structure shown in 
the SetEntries routine description. (These values are offsets into the srcTable, 
not the contents of the colorSpec.value field.) 


If a request is beyond the end of the dstTable, that position of the requestList 
is set to colRegErr, and an error is returned. Note that srcTable and selection 
are assumed to have the same number of entries. 


If dstTbl is NIL, or points to the device color table, the current device's 
color table is updated, and the hardware is updated to these new colors. The 
seed is not changed, so no invalidation occurs (this may cause RGBForeColor to 
act strangely). This routine ignores protection and reservation of color table 
entries. 
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Generally, the Palette Manager is used to give an application its own set of 
colors; use of RestoreEntries should be limited to special-purpose applications. 
RestoreEntries allows you to change the colorTable without changing the ctSeed 
for the affected colorTable. You can execute the application code and then use 
RestoreEntries to put the original colors back in. However, in some cases things 
in the background may appear in the wrong colors, since they were never redrawn. 
To avoid this, the application must build its own new inverse table and redraw 
the background. If RestoreEntries were then used, the ctSeed would have to be 
explicitly changed to clean up correctly. 


Error Handling 
FUNCTION QDError: INTEGER; 


The QDError routine returns the error result from the last QuickDraw or Color 
Manager call. This routine is even more useful with 32-Bit QuickDraw. It is 
important that you check for errors after every QuickDraw call. For more 
information, see the 32-Bit QuickDraw documentation. 
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CUSTOM SEARCH AND COMPLEMENT FUNCTIONS 


The custom search function allows an application to override the inverse table 
matching code. The desired color is specified in the RGBColor field of a 
ColorSpec record and passed via a pointer on the stack; the procedure returns 
the corresponding pixel value in the ColorSpec.value field. 


A custom search routine can provide its own matching rules. For instance, you 
might want to map all levels of green to a single green on a monitor. To do 
this, you could write and install a custom search procedure that is passed the 
RGB under question by the Color Manager. It can then analyze the color, and if 
it decides to act on this color, it can return the index of the desired shade of 
green. Otherwise, it can pass the color back to the Color Manager for matching, 
using the normal inverse table routine. 


Many applications can share the same graphics device, each with its own custom 
search procedure. The procedures are chain elements in a linked list beginning 
in the gdSearchProc field of the gDevice port: 


TYPE 
SProcHndl = “SProcPtr; 
SProcPtr = “SProcRec;; 
SProcRec = RECORD 
nxtSrch: SProcHndl; {handle to next sProcRec} 
srchProc: ProcPtr {pointer to search procedure} 
END; 


Any number of search procedures can be installed in a linked list, each element 
of which will be called sequentially by the Color Manager, and given the chance 
to act or pass on the color. Since each device is a shared resource, a simple 
method (the gdID) is provided to identify the caller to the search procedures, 
as well as routines to add and delete custom procedures from the linked list. 


The interface is as follows: 
FUNCTION SearchProc (rgb: RGBColor; VAR position: LONGINT): BOOLEAN; 


When attempting to approximate a color, the Color Manager calls each search 
procedure in the list until the boolean value returns as TRUE. The index value 
of the closest match is returned by the position parameter. If no search 
procedure installed in the linked list returns TRUE, the Color Manager calls the 
default search procedure. 


The application can also supply a custom complement procedure to find the 
complement of a specified color. Complement procedures work the same as search 
procedures, and are kept in a list beginning in the gDevice port's gdCompProc 
field. 


TYPE 
CProcHndl = *CProcPtr; 
CProcPtr = *CProcRec; 
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CProcRec = RECORD 


nxtComp: CProcHandle; {pointer to next CProcRec} 
compProc: ProcPtr {pointer to complement procedure} 
END; 


The default complement procedure simply uses the 1's complement of the RGB color 
components before looking them up in the inverse table. The interface is as 
follows: 


FUNCTION CompProc (VAR rgb: RGBColor) : BOOLEAN; 


Operations on Search and Complement Functions 


PROCEDURE AddSearch (searchProc: ProcPtr); 
PROCEDURE AddComp (compProc: ProcPtr); 


The AddSearch and AddComp routines add a procedure to the head of the current 
device record's list of search or complement procedures. These routines allocate 
an SProcRec or CProcRec. 


PROCEDURE DelSearch (searchProc: ProcPtr); 
PROCEDURE DelComp (compProc: ProcPtr); 


The DelSearch and DelComp procedures remove a custom search or complement 
procedure from the current device record's list of search or complement 
procedures. These routines dispose of the chain element, but do nothing to the 
procPtr. 


PROCEDURE SetClientID (id: INTEGER) ; 


The SetClientID procedure sets the gdID field in the current device record to 
identify this client program to its search and complement procedures. 
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SUMMARY OF THE COLOR MANAGER 


Constants 


CONST 
minSeed = 1023; 


{minimum seed value for ctSeed} 


Data Types 
TYPE 
ITabHandle = “ITabPtr; 
ITabPtr = “TTab; 
ITab = RECORD 
iTabSeed: LONGINT; {copy of color table seed} 
iTabRes: INTEGER; {resolution of table} 
iTTable: ARRAY[@..0] OF SignedByte {byte color } 
{ table index values} 
END; 
SProcHndl = *SProcPtr; 
SProcPtr = “SProcRec;; 
SProcRec = RECORD 
nxtSrch: SProcHndl; {handle to next sProcRec} 
srchProc: ProcPtr {pointer to search procedure} 
END; 
CProcHndl = *CProcPtr; 
CProcPtr = *CProcRec; 
CProcRec = RECORD 
nxtComp: CProcHandle; {pointer to next CProcRec} 
compProc: ProcPtr {pointer to complement procedure} 
END; 
ReqListRec = RECORD 
reqLSize: INTEGER; {request list size -—1} 
reqLData: ARRAY [0..0] of INTEGER {request list data} 


END; 


Routines 
Color Conversion 


FUNCTION Color2Index 
PROCEDURE Index2Color 
PROCEDURE InvertColor 
FUNCTION RealColor 

PROCEDURE GetSubTable 


(VAR rgb: RGBColor): LONGINT; 

(index: LONGINT; VAR rgb: RGBColor); 
(VAR theColor: RGBColor); 

(color: RGBColor) : BOOLEAN; 

(myColors: CTabHandle; iTabRes: INTEGER; 
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targetTbl:CTabHandle) ; 


PROCEDURE MakeITable (colorTab: CTabHandle; inverseTab: ITabHandle; 


res: INTEGER); 
Color Table Management 


FUNCTION GetCTSeed: LONGINT; 


PROCEDURE ProtectEntry (index: INTEGER; protect: BOOLEAN) ; 
index: INTEGER; reserve: BOOLEAN); 


PROCEDURE ReserveEntry 


( 
PROCEDURE SetEntries (start, count: INTEGER; aTable: cSpecArray) ; 
( 


PROCEDURE RestoreEntries 
VAR selection:ReqListRec) ; 


srclable:CTabHandle;dstTable:CTabHandle; 


PROCEDURE SaveEntries (srcTable:CTabHandle; resultTable:CTabHandle; VAR 


selection:ReqListRec) 

Operations on Search and Complement Functions 
PROCEDURE AddSearch (searchProc: ProcPtr); 
PROCEDURE AddComp (compProc: ProcPtr); 
PROCEDURE DelSearch (searchProc: ProcPtr); 
PROCEDURE DelComp (compProc: ProcPtr); 
PROCEDURE SetClientID (id: INTEGER); 

Error Handling 


FUNCTION QDError: INTEGER; 


Assembly Language Information 
Constants 
minSeed EQU 1023 ;minimum ctSeed value 


ITab structure 


iTabSeed EQU $0 ;[long] ID of owning color table 
iTabRes EQU $4 s[word] client ID 
iTTable EQU $6 stable of indices starts here 


sin this version, entries are BYTE 
SProcRec structure 


nxtSrch EQU $0 ;[pointer] link to next proc 
srchProc EQU $4 ;[pointer] pointer to routine 


CProcRec structure 


nxtComp EQU $0 ;[pointer] link to next proc 
compProc EQU $4 ;[pointer] pointer to routine 


Request list structure 


reqLSize  EQU 0 ; [word] request list size —1 
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reqLData EQU 2 ; [word] request list data 
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Further Reference: 


Color QuickDraw 

Graphics Devices 

Palette Manager 

Color Picker Package 

32-Bit QuickDraw Documentation 


END OF DOCUMENT 
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